<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>cpp_int</title>
<link rel="stylesheet" href="../../../multiprecision.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../ints.html" title="Integer Types">
<link rel="prev" href="../ints.html" title="Integer Types">
<link rel="next" href="gmp_int.html" title="gmp_int">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../ints.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ints.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gmp_int.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_multiprecision.tut.ints.cpp_int"></a><a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
</h4></div></div></div>
<p>
          <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_int</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
        </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">multiprecision</span><span class="special">{</span>

<span class="keyword">typedef</span> <span class="identifier">unspecified</span><span class="special">-</span><span class="identifier">type</span> <span class="identifier">limb_type</span><span class="special">;</span>

<span class="keyword">enum</span> <span class="identifier">cpp_integer_type</span>    <span class="special">{</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span> <span class="special">};</span>
<span class="keyword">enum</span> <span class="identifier">cpp_int_check_type</span>  <span class="special">{</span> <span class="identifier">checked</span><span class="special">,</span> <span class="identifier">unchecked</span> <span class="special">};</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">MinBits</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span>
          <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">MaxBits</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span>
          <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span> <span class="special">=</span> <span class="identifier">signed_magnitude</span><span class="special">,</span>
          <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span> <span class="special">=</span> <span class="identifier">unchecked</span><span class="special">,</span>
          <span class="keyword">class</span> <span class="identifier">Allocator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="identifier">limb_type</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">cpp_int_backend</span><span class="special">;</span>
<span class="comment">//</span>
<span class="comment">// Expression templates default to et_off if there is no allocator:</span>
<span class="comment">//</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">expression_template_default</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>
<span class="special">{</span> <span class="keyword">static</span> <span class="keyword">const</span> <span class="identifier">expression_template_option</span> <span class="identifier">value</span> <span class="special">=</span> <span class="identifier">et_off</span><span class="special">;</span> <span class="special">};</span>

<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>              <span class="identifier">cpp_int</span><span class="special">;</span>    <span class="comment">// arbitrary precision integer</span>
<span class="keyword">typedef</span> <span class="identifier">rational_adaptor</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;&gt;</span> <span class="special">&gt;</span>    <span class="identifier">cpp_rational_backend</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_rational_backend</span><span class="special">&gt;</span>            <span class="identifier">cpp_rational</span><span class="special">;</span> <span class="comment">// arbitrary precision rational number</span>

<span class="comment">// Fixed precision unsigned types:</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint128_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint256_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">uint512_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">uint1024_t</span><span class="special">;</span>

<span class="comment">// Fixed precision signed types:</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int128_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int256_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">int512_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">unchecked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">int1024_t</span><span class="special">;</span>

<span class="comment">// Over again, but with checking enabled this time:</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">&gt;</span> <span class="special">&gt;</span>                 <span class="identifier">checked_cpp_int</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">rational_adaptor</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_cpp_rational_backend</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_rational_backend</span><span class="special">&gt;</span>                                              <span class="identifier">checked_cpp_rational</span><span class="special">;</span>

<span class="comment">// Checked fixed precision unsigned types:</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint128_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint256_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_uint512_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">unsigned_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>   <span class="identifier">checked_uint1024_t</span><span class="special">;</span>

<span class="comment">// Fixed precision signed types:</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">128</span><span class="special">,</span> <span class="number">128</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int128_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">256</span><span class="special">,</span> <span class="number">256</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int256_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">512</span><span class="special">,</span> <span class="number">512</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>       <span class="identifier">checked_int512_t</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_int_backend</span><span class="special">&lt;</span><span class="number">1024</span><span class="special">,</span> <span class="number">1024</span><span class="special">,</span> <span class="identifier">signed_magnitude</span><span class="special">,</span> <span class="identifier">checked</span><span class="special">,</span> <span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>     <span class="identifier">checked_int1024_t</span><span class="special">;</span>

<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<p>
          The <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code> type
          is normally used via one of the convenience typedefs given above.
        </p>
<p>
          This back-end is the "Swiss Army Knife" of integer types as it
          can represent both fixed and <a href="http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic" target="_top">arbitrary
          precision</a> integer types, and both signed and unsigned types. There
          are five template arguments:
        </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">MinBits</span></dt>
<dd><p>
                Determines the number of Bits to store directly within the object
                before resorting to dynamic memory allocation. When zero, this field
                is determined automatically based on how many bits can be stored
                in union with the dynamic storage header: setting a larger value
                may improve performance as larger integer values will be stored internally
                before memory allocation is required.
              </p></dd>
<dt><span class="term">MaxBits</span></dt>
<dd><p>
                Determines the maximum number of bits to be stored in the type: resulting
                in a fixed precision type. When this value is the same as MinBits,
                then the Allocator parameter is ignored, as no dynamic memory allocation
                will ever be performed: in this situation the Allocator parameter
                should be set to type <code class="computeroutput"><span class="keyword">void</span></code>.
                Note that this parameter should not be used simply to prevent large
                memory allocations, not only is that role better performed by the
                allocator, but fixed precision integers have a tendency to allocate
                all of MaxBits of storage more often than one would expect.
              </p></dd>
<dt><span class="term">SignType</span></dt>
<dd><p>
                Determines whether the resulting type is signed or not. Note that
                for <a href="http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic" target="_top">arbitrary
                precision</a> types this parameter must be <code class="computeroutput"><span class="identifier">signed_magnitude</span></code>.
                For fixed precision types then this type may be either <code class="computeroutput"><span class="identifier">signed_magnitude</span></code> or <code class="computeroutput"><span class="identifier">unsigned_magnitude</span></code>.
              </p></dd>
<dt><span class="term">Checked</span></dt>
<dd><p>
                This parameter has two values: <code class="computeroutput"><span class="identifier">checked</span></code>
                or <code class="computeroutput"><span class="identifier">unchecked</span></code>. See
                below.
              </p></dd>
<dt><span class="term">Allocator</span></dt>
<dd><p>
                The allocator to use for dynamic memory allocation, or type <code class="computeroutput"><span class="keyword">void</span></code> if MaxBits == MinBits.
              </p></dd>
</dl>
</div>
<p>
          When the template parameter Checked is set to <code class="computeroutput"><span class="identifier">checked</span></code>
          then the result is a <span class="emphasis"><em>checked-integer</em></span>, checked and
          unchecked integers have the following properties:
        </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                  <p>
                    Condition
                  </p>
                </th>
<th>
                  <p>
                    Checked-Integer
                  </p>
                </th>
<th>
                  <p>
                    Unchecked-Integer
                  </p>
                </th>
</tr></thead>
<tbody>
<tr>
<td>
                  <p>
                    Numeric overflow in fixed precision arithmetic
                  </p>
                </td>
<td>
                  <p>
                    Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>.
                  </p>
                </td>
<td>
                  <p>
                    Performs arithmetic modulo 2<sup>MaxBits</sup>
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Constructing an integer from a value that can not be represented
                    in the target type
                  </p>
                </td>
<td>
                  <p>
                    Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>.
                  </p>
                </td>
<td>
                  <p>
                    Converts the value modulo 2<sup>MaxBits</sup>, signed to unsigned conversions
                    extract the last MaxBits bits of the 2's complement representation
                    of the input value.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Unsigned subtraction yielding a negative value.
                  </p>
                </td>
<td>
                  <p>
                    Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>.
                  </p>
                </td>
<td>
                  <p>
                    Yields the value that would result from treating the unsigned
                    type as a 2's complement signed type.
                  </p>
                </td>
</tr>
<tr>
<td>
                  <p>
                    Attempting a bitwise operation on a negative value.
                  </p>
                </td>
<td>
                  <p>
                    Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code>
                  </p>
                </td>
<td>
                  <p>
                    Yields the value, but not the bit pattern, that would result
                    from performing the operation on a 2's complement integer type.
                  </p>
                </td>
</tr>
</tbody>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            When an exception is thrown as a result of using a checked type, then
            the value of the target operand after the exception is caught is unspecified.
          </p></td></tr>
</table></div>
<p>
          Things you should know when using this type:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              Default constructed <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code>s
              have the value zero.
            </li>
<li class="listitem">
              Division by zero results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code>
              being thrown.
            </li>
<li class="listitem">
              Construction from a string that contains invalid non-numeric characters
              results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code> being thrown.
            </li>
<li class="listitem">
              Since the precision of <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code>
              is necessarily limited when the allocator parameter is void, care should
              be taken to avoid numeric overflow when using this type unless you
              actually want modulo-arithmetic behavior.
            </li>
<li class="listitem">
              The type uses a sign-magnitude representation internally, so type
              <code class="computeroutput"><span class="identifier">int128_t</span></code> has 128-bits
              of precision plus an extra sign bit. In this respect the behaviour
              of these types differs from <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
              (built-in)</a> 2's complement types. In might be tempting to use
              a 127-bit type instead, and indeed this does work, but behaviour is
              still slightly different from a 2's complement <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
              (built-in)</a> type as the minimum and maximum values are identical
              (apart from the sign), where as they differ by one for a true 2's complement
              type. That said it should be noted that there's no requirement for
              fundamental_types to be 2's complement either - it's simply that this
              is the most common format by far.
            </li>
<li class="listitem">
              Attempting to print negative values as either an Octal or Hexadecimal
              string results in a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
              being thrown, this is a direct consequence of the sign-magnitude representation.
            </li>
<li class="listitem">
              The fixed precision types <code class="computeroutput"><span class="special">[</span><span class="identifier">checked_</span><span class="special">][</span><span class="identifier">u</span><span class="special">]</span><span class="identifier">intXXX_t</span></code> have expression template
              support turned off - it seems to make little difference to the performance
              of these types either way - so we may as well have the faster compile
              times by turning the feature off.
            </li>
<li class="listitem">
              Unsigned types support subtraction - the result is "as if"
              a 2's complement operation had been performed as long as they are not
              <span class="emphasis"><em>checked-integers</em></span> (see above). In other words they
              behave pretty much as a <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
              (built-in)</a> integer type would in this situation. So for example
              if we were using <code class="computeroutput"><span class="identifier">uint128_t</span></code>
              then <code class="computeroutput"><span class="identifier">uint128_t</span><span class="special">(</span><span class="number">1</span><span class="special">)-</span><span class="number">4</span></code>
              would result in the value <code class="computeroutput"><span class="number">0</span><span class="identifier">xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD</span></code>
              of type <code class="computeroutput"><span class="identifier">uint128_t</span></code>.
              However, had this operation been performed on <code class="computeroutput"><span class="identifier">checked_uint128_t</span></code>
              then a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">range_error</span></code> would have been thrown.
            </li>
<li class="listitem">
              Unary negation of unsigned types results in a compiler error (static
              assertion).
            </li>
<li class="listitem">
              This backend supports rvalue-references and is move-aware, making instantiations
              of <code class="computeroutput"><span class="identifier">number</span></code> on this backend
              move aware.
            </li>
<li class="listitem">
              When used at fixed precision, the size of this type is always one machine
              word (plus any compiler-applied alignment padding) larger than you
              would expect for an N-bit integer: the extra word stores both the sign,
              and how many machine words in the integer are actually in use. The
              latter is an optimisation for larger fixed precision integers, so that
              a 1024-bit integer has almost the same performance characteristics
              as a 128-bit integer, rather than being 4 times slower for addition
              and 16 times slower for multiplication (assuming the values involved
              would always fit in 128 bits). Typically this means you can use an
              integer type wide enough for the "worst case scenario" with
              only minor performance degradation even if most of the time the arithmetic
              could in fact be done with a narrower type. Also note that unsigned
              fixed precision types small enough to fit inside the largest native
              integer become a simple wrapper around that type, this includes the
              "checked" variants. Small signed types will always have an
              extra sign word and so be larger than their native equivalent.
            </li>
<li class="listitem">
              When used at fixed precision and MaxBits is smaller than the number
              of bits in the largest native integer type, then internally <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code> switches to a "trivial"
              implementation where it is just a thin wrapper around a single integer.
              Note that it will still be slightly slower than a bare native integer,
              as it emulates a signed-magnitude representation rather than simply
              using the platforms native sign representation: this ensures there
              is no step change in behavior as a cpp_int grows in size.
            </li>
<li class="listitem">
              Fixed precision <code class="computeroutput"><span class="identifier">cpp_int</span></code>'s
              have some support for <code class="computeroutput"><span class="keyword">constexpr</span></code>
              values and user-defined literals, see <a class="link" href="../lits.html" title="Literal Types and constexpr Support">here</a>
              for the full description. For example <code class="computeroutput"><span class="number">0xfffff</span><span class="identifier">_cppi1024</span></code> specifies a 1024-bit integer
              with the value 0xffff. This can be used to generate compile-time constants
              that are too large to fit into any <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
              (built-in)</a> number type.
            </li>
<li class="listitem">
              The <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
              types support constexpr arithmetic, provided it is a fixed-precision
              type with no allocator. It may also be a checked integer: in which
              case a compiler error will be generated on overflow or undefined behaviour.
              In addition the free functions <code class="computeroutput"><span class="identifier">abs</span></code>,
              <code class="computeroutput"><span class="identifier">swap</span></code>, <code class="computeroutput"><span class="identifier">multiply</span></code>, <code class="computeroutput"><span class="identifier">add</span></code>,
              <code class="computeroutput"><span class="identifier">subtract</span></code>, <code class="computeroutput"><span class="identifier">divide_qr</span></code>, <code class="computeroutput"><span class="identifier">integer_modulus</span></code>,
              <code class="computeroutput"><span class="identifier">powm</span></code>, <code class="computeroutput"><span class="identifier">lsb</span></code>, <code class="computeroutput"><span class="identifier">msb</span></code>,
              <code class="computeroutput"><span class="identifier">bit_test</span></code>, <code class="computeroutput"><span class="identifier">bit_set</span></code>, <code class="computeroutput"><span class="identifier">bit_unset</span></code>,
              <code class="computeroutput"><span class="identifier">bit_flip</span></code>, <code class="computeroutput"><span class="identifier">sqrt</span></code>, <code class="computeroutput"><span class="identifier">gcd</span></code>,
              <code class="computeroutput"><span class="identifier">lcm</span></code> are all supported.
              Use of <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
              in this way requires either a C++2a compiler (one which supports <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">is_constant_evaluated</span><span class="special">()</span></code>),
              or GCC-6 or later in C++14 mode. Compilers other than GCC and without
              <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">is_constant_evaluated</span><span class="special">()</span></code>
              will support a very limited set of operations: expect to hit roadblocks
              rather easily.
            </li>
<li class="listitem">
              You can import/export the raw bits of a <a class="link" href="cpp_int.html" title="cpp_int">cpp_int</a>
              to and from external storage via the <code class="computeroutput"><span class="identifier">import_bits</span></code>
              and <code class="computeroutput"><span class="identifier">export_bits</span></code> functions.
              More information is in the <a class="link" href="../import_export.html" title="Importing and Exporting Data to and from cpp_int and cpp_bin_float">section
              on import/export</a>.
            </li>
</ul></div>
<h6>
<a name="boost_multiprecision.tut.ints.cpp_int.h0"></a>
          <span class="phrase"><a name="boost_multiprecision.tut.ints.cpp_int.cpp_int_eg"></a></span><a class="link" href="cpp_int.html#boost_multiprecision.tut.ints.cpp_int.cpp_int_eg">Example:</a>
        </h6>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_int</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
<span class="special">{</span>
   <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">;</span>

   <span class="identifier">int128_t</span> <span class="identifier">v</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>

   <span class="comment">// Do some fixed precision arithmetic:</span>
   <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;=</span> <span class="number">20</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
      <span class="identifier">v</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span>

   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// prints 2432902008176640000 (i.e. 20!)</span>

   <span class="comment">// Repeat at arbitrary precision:</span>
   <span class="identifier">cpp_int</span> <span class="identifier">u</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
   <span class="keyword">for</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;=</span> <span class="number">100</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
      <span class="identifier">u</span> <span class="special">*=</span> <span class="identifier">i</span><span class="special">;</span>

   <span class="comment">// prints 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000 (i.e. 100!)</span>
   <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">u</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

   <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span>
</pre>
</div>
<div class="copyright-footer">Copyright © 2002-2020 John
      Maddock and Christopher Kormanyos<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../ints.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ints.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="gmp_int.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
